📜 add chart api documentation #3473
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
Quick links (staging server):
Login: chart-diff: ✅No charts for review.data-diff: ✅ No differences foundLegend: +New ~Modified -Removed =Identical Details
Hint: Run this locally with etl diff REMOTE data/ --include yourdataset --verbose --snippetAutomatically updated datasets matching weekly_wildfires|excess_mortality|covid|fluid|flunet|country_profile|garden/ihme_gbd/2019/gbd_risk are not included Edited: 2024-11-01 14:55:34 UTC |
Marigold
approved these changes
Oct 31, 2024
There was a problem hiding this comment.
Nice addition! I've added a commit to fix rendering of docs as index.md is created dynamically. You can check docs on the staging server at http://staging-site-chart-api-docs/etl/docs/api/.
marcelgerber
approved these changes
Oct 31, 2024
docs/api/index.md
Outdated
|
|
||
| When using the API, you have access to the public catalog of data processed by our data team. The catalog indexes _tables_ of data, rather than datasets or individual indicators. To learn more, read about our [data model](../architecture/design/common-format.md). | ||
| We also have a larger data catalog in our ETL. This is the space where we fetch, process and prepare the data used in our charts. It contains substantially more data but it is curated to different degrees in different parts. It also offers an API although one that is less straightforward to access - for now we offer only a Python client to interact with this API. This data is structured according to our internal needs and varies a lot more in shape than the data in the public charts API - e.g. the public charts API only has time series data using time (usually the year) and entity (usually the country), whereas our ETL often has much larger datasets than contain additional dimensions like a breakdown by age group and gender. |
There was a problem hiding this comment.
Suggested change
| We also have a larger data catalog in our ETL. This is the space where we fetch, process and prepare the data used in our charts. It contains substantially more data but it is curated to different degrees in different parts. It also offers an API although one that is less straightforward to access - for now we offer only a Python client to interact with this API. This data is structured according to our internal needs and varies a lot more in shape than the data in the public charts API - e.g. the public charts API only has time series data using time (usually the year) and entity (usually the country), whereas our ETL often has much larger datasets than contain additional dimensions like a breakdown by age group and gender. | |
| We also have a larger data catalog in our ETL. This is the space where we fetch, process and prepare the data used in our charts. It contains substantially more data but it is curated to different degrees in different parts. It also offers an API although one that is less straightforward to access - for now we offer only a Python client to interact with this API. This data is structured according to our internal needs and varies a lot more in shape than the data in the public charts API - e.g. the public charts API only has time series data using time (usually the year) and entity (usually the country), whereas our ETL often has much larger datasets that contain additional dimensions like a breakdown by age group and gender. |
docs/api/index.md
Outdated
|
|
||
| The third column is either "Year" or "Day". If the data is annual, this is "Year" and contains only the year as an integer. If the column is "Day", the column contains a date string in the form "YYYY-MM-DD". | ||
|
|
||
| The final columns are the data columns, which are the time series that powers the chart. For simple line charts there is only a single data column, more complex charts can have more columns. |
There was a problem hiding this comment.
Suggested change
| The final columns are the data columns, which are the time series that powers the chart. For simple line charts there is only a single data column, more complex charts can have more columns. | |
| The final columns are the data columns, which are the time series that powers the chart. For simple line charts there is only a single data column, whereas more complex charts can have more columns. |
docs/api/index.md
Outdated
| "subtitle": "The [period life expectancy](#dod:period-life-expectancy) at birth, in a given year.", | ||
| "citation": "UN WPP (2022); HMD (2023); Zijdeman et al. (2015); Riley (2005)", | ||
| "originalChartUrl": "https://ourworldindata.org/grapher/life-expectancy", | ||
| "selection": ["World", "Americas", "Europe","Africa","Asia","Oceania"] |
There was a problem hiding this comment.
Suggested change
| "selection": ["World", "Americas", "Europe","Africa","Asia","Oceania"] | |
| "selection": ["World", "Americas", "Europe", "Africa", "Asia", "Oceania"] |
|
@Marigold @marcelgerber thanks a lot for your input! |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR adds a first stab at describing how our new chart data api works. Feedback is welcome!